home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Programming / jpeglibrary / autodocs / jpeg.autodoc
Encoding:
Text File  |  1998-05-26  |  14.9 KB  |  506 lines
  1. TABLE OF CONTENTS
  2.  
  3. jpeg.library/--background--
  4. jpeg.library/--information--
  5. jpeg.library/AllocJPEGCompressA
  6. jpeg.library/AllocJPEGDecompressA
  7. jpeg.library/AllocRGBFromJPEGA
  8. jpeg.library/CompressJPEGA
  9. jpeg.library/DecompressJPEGA
  10. jpeg.library/FreeJPEGCompress
  11. jpeg.library/FreeJPEGDecompress
  12. jpeg.library/FreeJPEGRGBBuffer
  13. jpeg.library/GetJPEGInfoA
  14. jpeg.library/--background--                       jpeg.library/--background--
  15.  
  16.    PURPOSE
  17.  To allow de/compression of images into/from the jpeg image format.
  18.  
  19.    COPYRIGHT
  20.  The copyright in this library is owned by Paul Huxham.
  21.  This software is based in part on the work of the Independent JPEG Group.
  22.  The jpeg de/compression routines are copyright by the Independent
  23.  JPEG Group, written by Thomas G. Lane.
  24.  
  25.    DISCLAIMER
  26.  jpeg.library and its associated files are supposed to enable jpeg images
  27.  to be de/compressed. Even though every effort has been made to make
  28.  jpeg.library as stable and functional as possible, I cannot rule out the
  29.  possibility that jpeg.library may have bugs that have side effects
  30.  (possibly harmful) on your system.
  31.  
  32.  I hereby reject any liability or responsibility for these or any other
  33.  consequences from the use of jpeg.library whatsoever. This includes, but
  34.  is not limited to, damage to your equipment, to your data, personal
  35.  injuries, financial loss or any other kinds of side effects.
  36.  
  37.  jpeg.library is provided as-is. This means I do not guarantee that
  38.  jpeg.library is fit for any specific purpose and I do not guarantee any
  39.  bug fixes, updates or help during error recovery.
  40.  
  41.    DISTRIBUTION
  42.  jpeg.library should be distributed at no charge to the end user. It may
  43.  be included on Aminet CDs.
  44.  
  45.  The author retains all rights to the enclosed software. Payment is not
  46.  required for the use of jpeg.library.
  47.  
  48.    CONTENTS
  49.  jpeg.library - The jpeg de/compression library.
  50.  jpeg_protos.h - The function prototypes.
  51.  jpeg_pragmas.h - The function pragmas.
  52.  jpeg.h - proof.library definitions.
  53.  jpeg.lib - Stubs link library.
  54.  jpeg.autodoc - jpeg.library documentation.
  55.  
  56.    REQUIREMENTS
  57.  A minimum of Kickstart 2.0 and 68020 CPU is required to use jpeg.library.
  58.  
  59.    COMPLIER
  60.  jpeg.library was written and compiled using CED V3.5 and SAS/C 6.55 on
  61.  an Amiga 4000/060. CyberGuard was used to detect/correct programming
  62.  errors.
  63.  
  64.    BUGS
  65.  Should you find any bugs, please report them so that they can be fixed.
  66.  Likewise any suggestions for improvment of the library should be
  67.  forwarded so that they can be addressed.
  68.  
  69.    THANKYOUS
  70.  Many thanks to
  71.    Dinh Thi Kim Tuyen
  72.      -Who makes the sky blue and the world turn. I love you, forevermore.
  73.  
  74.    Steve Quartly
  75.      - For saying its possible and then helping me do it.
  76.  
  77.    AUTHORS
  78.   You can contact the author via:
  79.     email: paulh@mafeking.scouts.org.au
  80.   or
  81.     P.O. Box 875
  82.     Morley,
  83.     Perth,
  84.     Western Australia 6943
  85.  
  86. jpeg.library/--information--                     jpeg.library/--information--
  87.  
  88.  Although the documentation is not extensive, the examples are fairly well
  89.  layed out and easy to follow. They all use different methods of
  90.  accessing jpeg.library. You can choose the one that suits your
  91.  application best.
  92.  
  93.  It is EXTREMELY IMPORTANT to check the colour space of the jpeg image you
  94.  have decoded (or are about to decode). For example, in a JPCS_GRAYSCALE
  95.  only the first third of the rgb triplet buffer will be filled with data
  96.  as the grayscale image data is normally one byte per pixel. For
  97.  JPCS_UNKNOWN, check the number of bytes per pixel to establish if the
  98.  data is grayscale or not. For JPCS_RGB, the image data will be returned
  99.  as an rgb triplet array.
  100.  
  101. jpeg.library/AllocJPEGCompressA               jpeg.library/AllocJPEGCompressA
  102.  
  103.    NAME
  104.   AllocJPEGCompressA -- Allocate a jpeg compression handle (V1)
  105.   AllocJPEGCompress -- Varargs stub (V1)
  106.  
  107.    SYNOPSIS
  108.  err = AllocJPEGCompressA( jph, taglist )
  109.                              a0   a1
  110.  
  111.  err = AllocJPEGCompressA( struct JPEGComHandle **jph,
  112.                              struct TagItem *taglist )
  113.  
  114.  err = AllocJPEGCompress( jph, tag1, ... )
  115.  
  116.  err = AllocJPEGCompress( struct JPEGComHandle **jph, ULONG tag1, ... )
  117.  
  118.    FUNCTION
  119.  Allocates a new jpeg handle.
  120.  
  121.   Available tags:
  122.    JPG_DestMemStream     - A pointer to a UBYTE pointer to take the data
  123.                            generated by the compressor (REQUIRED). See NOTE
  124.                            below about this allocated memory.
  125.    JPG_DestMemStreamSize - A pointer to a ULONG to take the size of the
  126.                            compressed data (REQUIRED).
  127.    JPG_DestFile          - A BPTR to an already open AmigaDOS file.
  128.  
  129.    INPUTS
  130.  jph - pointer to a struct JPEGComHandle pointer.
  131.  taglist - pointer to a tag list specifying the destination for the
  132.            compressed data and data size.
  133.  
  134.    RESULT
  135.  err - if non NULL contains an error code. (For a complete list of error
  136.        codes, see jpeg.h)
  137.  
  138.    WARNING
  139.  
  140.    BUGS
  141.  
  142.    NOTES
  143.  You are responsible for freeing the memory allocated to you, by calling
  144.  FreeVec() on the pointer supplied to AllocJPEGCompress() (if it isnt a
  145.  NULL value).
  146.  
  147.    SEE ALSO
  148.  FreeJPEGCompressA(), CompressJPEGA()
  149.  
  150. jpeg.library/AllocJPEGDecompressA           jpeg.library/AllocJPEGDecompressA
  151.  
  152.    NAME
  153.   AllocJPEGDecompressA -- Allocate a jpeg decompression handle (V1)
  154.   AllocJPEGDecompress -- Varargs stub (V1)
  155.  
  156.    SYNOPSIS
  157.  err = AllocJPEGDecompressA( jph, taglist )
  158.                              a0   a1
  159.  
  160.  err = AllocJPEGDecompressA( struct JPEGDecHandle **jph,
  161.                              struct TagItem *taglist )
  162.  
  163.  err = AllocJPEGDecompress( jph, tag1, ... )
  164.  
  165.  err = AllocJPEGDecompress( struct JPEGDecHandle **jph, ULONG tag1, ... )
  166.  
  167.    FUNCTION
  168.  Allocates a new jpeg handle.
  169.  
  170.   Available tags:
  171.    JPG_SrcMemStream     - The source image is a segment of memory starting
  172.                           at this address.
  173.    JPG_SrcMemStreamSize - The length of the memory based segment, in bytes.
  174.    JPG_SrcFile          - A BPTR to an already open AmigaDOS file.
  175.  
  176.    INPUTS
  177.  jph - pointer to a struct JPEGDecHandle pointer.
  178.  taglist - pointer to a tag list specifying the jpeg stream source and
  179.            size.
  180.  
  181.    RESULT
  182.  err - if non NULL contains an error code. (For a complete list of error
  183.        codes, see jpeg.h)
  184.  
  185.    WARNING
  186.  
  187.    BUGS
  188.  
  189.    SEE ALSO
  190.  FreeJPEGDecompressA(), DecompressJPEGA()
  191.  
  192. jpeg.library/AllocRGBFromJPEGA                 jpeg.library/AllocRGBFromJPEGA
  193.  
  194.    NAME
  195.   AllocRGBFromJPEGA -- Allocate an RGB triplet buffer (V1)
  196.   AllocRGBFromJPEG -- Varargs stub (V1)
  197.  
  198.    SYNOPSIS
  199.  buffer = AllocRGBFromJPEGA( jph, taglist )
  200.                              a0   a1
  201.  
  202.  void *AllocRGBFromJPEGA( struct JPEGDecHandle *jph,
  203.                           struct TagItem *taglist )
  204.  
  205.  buffer = AllocRGBFromJPEG( jph, tag1, ... )
  206.  
  207.  void *AllocRGBFromJPEG( struct JPEGDecHandle *jph, ULONG tag1, ... )
  208.  
  209.    FUNCTION
  210.  Allocates enough memory to hold the decompressed version of the jpeg in
  211.  memory as a stream of RGB triplets.
  212.  
  213.    INPUTS
  214.  taglist  - pointer to an optional tag list specifying how to modify the
  215.             image data.
  216.  
  217.   Modifiers (used, but not saved in the jpeg handle):
  218.    JPG_ScaleNum      - Return values as though scaled with this value.
  219.    JPG_ScaleDenom    - Return values as though scaled with this value.
  220.  
  221.    RESULT
  222.  buffer - is NULL for any error, or a pointer to the memory allocated.
  223.  
  224.    WARNING
  225.  
  226.    BUGS
  227.  
  228.    NOTES
  229.  If you obtained your image sizes from GetJPEGInfo() and used scale tags,
  230.  you SHOULD also pass those same tag values to this function to allocate
  231.  the buffer, otherwise the buffer allocated will be the original size of
  232.  the image.
  233.  
  234.    SEE ALSO
  235.  FreeJPEGRGBBuffer()
  236.  
  237. jpeg.library/CompressJPEGA                         jpeg.library/CompressJPEGA
  238.  
  239.    NAME
  240.   CompressJPEGA -- Compress a jpeg stream (V1)
  241.   CompressJPEG -- Varargs stub (V1)
  242.  
  243.    SYNOPSIS
  244.  err = CompressJPEGA( jph, taglist )
  245.                         a0   a1
  246.  
  247.  err = CompressJPEGA( struct JPEGComHandle *jph,
  248.                         struct TagItem *taglist )
  249.  
  250.  err = CompressJPEG( jph, tag1, ... )
  251.  
  252.  err = CompressJPEG( struct JPEGComHandle **jph, ULONG tag1, ... )
  253.  
  254.    FUNCTION
  255.  Compresses a jpeg stream into the location specified by
  256.  AllocJPGCompress() using the supplied tags.
  257.  
  258.   Available tags:
  259.    JPG_SrcRGBBuffer      - An RGB triplet buffer containing the source
  260.                            image.
  261.    JPG_CompressHook      - Calls a user specified function (see jpeg.h)
  262.    JPG_CompressUserData  - User data passed to the hook function.
  263.    JPG_Width             - Width of the image (REQUIRED).
  264.    JPG_Height            - Height of the image (REQUIRED).
  265.    JPG_Quality           - Jpeg save quality (1-100), defaults to 85.
  266.    JPG_BytesPerPixel     - The number of bytes per image pixel, defaults
  267.                            to 3.
  268.    JPG_ColourSpace       - The type of image data stored in the buffer,
  269.                            defaults to JPCS_RGB (see jpeg.h for others).
  270.    JPG_Smoothing         - Apply image smoothing while saving (0-100),
  271.                            defaults to none (0).
  272.  
  273.    INPUTS
  274.  jph - pointer to a struct JPEGComHandle.
  275.  taglist - pointer to a tag list.
  276.  
  277.    RESULT
  278.  err - if non NULL contains an error code. (For a complete list of error
  279.        codes, see jpeg.h)
  280.  
  281.    WARNING
  282.  
  283.    BUGS
  284.  
  285.    NOTES
  286.  You are responsible for freeing the memory allocated to you, by calling
  287.  FreeVec() on the pointer supplied to AllocJPEGCompress().
  288.  e.g.
  289.  
  290.   UBYTE *cstream;
  291.   ULONG cstreamsize;
  292.  
  293.   err = AllocJPEGCompress( &jpc, JPG_DestMemStream, &cstream,
  294.           JPG_DestMemStreamSize, &cstreamsize, TAG_DONE );
  295.  
  296.   err = CompressJPEG( jpc, JPG_SrcRGBBuffer, buffer,
  297.           JPG_Width, x, JPG_Height, y, TAG_DONE );
  298.  
  299.   FreeJPEGCompress( jpc );
  300.  
  301.   /* Use the buffer here */
  302.  
  303.   if ( cstream != NULL ) FreeVec( cstream );
  304.  
  305.    SEE ALSO
  306.  AllocJPEGCompressA(), FreeJPEGCompressA()
  307.  
  308. jpeg.library/DecompressJPEGA                     jpeg.library/DecompressJPEGA
  309.  
  310.    NAME
  311.   DecompressJPEGA -- Decompress a jpeg stream (V1)
  312.   DecompressJPEG -- Varargs stub (V1)
  313.  
  314.    SYNOPSIS
  315.  err = DecompressJPEGA( jph, taglist )
  316.                         a0   a1
  317.  
  318.  err = DecompressJPEGA( struct JPEGDecHandle *jph,
  319.                         struct TagItem *taglist )
  320.  
  321.  err = DecompressJPEG( jph, tag1, ... )
  322.  
  323.  err = DecompressJPEG( struct JPEGDecHandle **jph, ULONG tag1, ... )
  324.  
  325.    FUNCTION
  326.  Decompresses a jpeg stream as specified by AllocJPGDecompress() and
  327.  supplied tags.
  328.  
  329.   Available tags:
  330.    JPG_DestRGBBuffer      - The decompressed image data is stored as RGB
  331.                             triplets starting at this address. You must
  332.                             allocate enough memory to take the image. Use
  333.                             AllocRGBFromJPEG() to allocate the required
  334.                             memory space.
  335.    JPG_DecompressHook     - Calls a user specified function (see jpeg.h).
  336.                             DO NOT pass a hook structure pointer here. Put
  337.                             a pointer to your function. (See examples)
  338.    JPG_DecompressUserData - User data passed to the hook function (void *).
  339.    JPG_ScaleNum           - Scale decompressed data with this value.
  340.    JPG_ScaleDenom         - Scale decompressed data with this value.
  341.  
  342.  The jpeg code has a limition on scaling where, num must always be 1 and
  343.  denom can be either: 1, 2, 4, or 8.
  344.  
  345.    INPUTS
  346.  jph - pointer to a struct JPEGDecHandle.
  347.  taglist - pointer to a tag list.
  348.  
  349.    RESULT
  350.  err - if non NULL contains an error code. (For a complete list of error
  351.        codes, see jpeg.h)
  352.  
  353.    WARNING
  354.  
  355.    BUGS
  356.  
  357.    SEE ALSO
  358.  AllocJPEGDecompressA(), FreeJPEGDecompressA()
  359.  
  360. jpeg.library/FreeJPEGCompress                   jpeg.library/FreeJPEGCompress
  361.  
  362.    NAME
  363.   FreeJPEGCompress -- Free a jpeg compression handle (V1)
  364.  
  365.    SYNOPSIS
  366.  err = FreeJPEGCompress( jph )
  367.                             a0
  368.  
  369.  err = FreeJPEGCompress( struct JPEGComHandle *jph )
  370.  
  371.    FUNCTION
  372.  Frees a jpeg handle.
  373.  
  374.    INPUTS
  375.  jph - pointer to a struct JPEGComHandle.
  376.  
  377.    RESULT
  378.  err - if non NULL contains an error code. (For a complete list of error
  379.        codes, see jpeg.h)
  380.  
  381.    WARNING
  382.  
  383.    BUGS
  384.  
  385.    NOTES
  386.  You are responsible for freeing the memory allocated to you by
  387.  CompressJPEG(), by calling FreeVec() on the pointer supplied to
  388.  AllocJPEGCompress().
  389.  
  390.    SEE ALSO
  391.  AllocJPEGCompressA(), CompressJPEGA()
  392.  
  393. jpeg.library/FreeJPEGDecompress               jpeg.library/FreeJPEGDecompress
  394.  
  395.    NAME
  396.   FreeJPEGDecompress -- Free a jpeg decompression handle (V1)
  397.  
  398.    SYNOPSIS
  399.  err = FreeJPEGDecompress( jph )
  400.                             a0
  401.  
  402.  err = FreeJPEGDecompress( struct JPEGDecHandle *jph )
  403.  
  404.    FUNCTION
  405.  Frees a jpeg handle.
  406.  
  407.    INPUTS
  408.  jph - pointer to a struct JPEGDecHandle.
  409.  
  410.    RESULT
  411.  err - if non NULL contains an error code. (For a complete list of error
  412.        codes, see jpeg.h)
  413.  
  414.    WARNING
  415.  
  416.    BUGS
  417.  
  418.    SEE ALSO
  419.  AllocJPEGDecompressA(), DecompressJPEGA()
  420.  
  421. jpeg.library/FreeJPEGRGBBuffer                 jpeg.library/FreeJPEGRGBBuffer
  422.  
  423.    NAME
  424.   FreeJPEGRGBBuffer -- Free an RGB triplet buffer (V1)
  425.  
  426.    SYNOPSIS
  427.  FreeJPEGRGBBuffer( buffer )
  428.                     a0
  429.  
  430.  void FreeJPEGRGBBuffer( void *buffer )
  431.  
  432.    FUNCTION
  433.  Frees an RGB triplet buffer allocated with AllocRGBFromJPEGA().
  434.  
  435.    INPUTS
  436.  buffer - Pointer to the allocated buffer returned by AllocRGBFromJPEG().
  437.  
  438.    RESULT
  439.  
  440.    WARNING
  441.  
  442.    BUGS
  443.  
  444.    SEE ALSO
  445.  AllocRGBFromJPEG()
  446.  
  447. jpeg.library/GetJPEGInfoA                           jpeg.library/GetJPEGInfoA
  448.  
  449.    NAME
  450.   GetJPEGInfoA -- Get information about a jpeg handle (V1)
  451.   GetJPEGInfo -- Varargs stub (V1)
  452.  
  453.    SYNOPSIS
  454.  err = GetJPEGInfoA( jph, taglist )
  455.                      a0   a1
  456.  
  457.  err = GetJPEGInfoA( struct JPEGDecHandle *jph, struct TagItem *taglist )
  458.  
  459.  err = GetJPEGInfo( jph, tag1, ... )
  460.  
  461.  err = GetJPEGInfo( struct JPEGDecHandle *jph, ULONG tag1, ... )
  462.  
  463.    FUNCTION
  464.  Retrieves information about the jpeg handle and returns the values in
  465.  variables passed in with the taglist.
  466.  
  467.   Available tags:
  468.    JPG_Width         - Returns the width of the decoded image (ULONG).
  469.    JPG_Height        - Returns the height of the decoded image (ULONG).
  470.    JPG_BytesPerPixel - Returns the number of bytes for every pixel,
  471.                        (usually 3) (ULONG).
  472.    JPG_RowSize       - Returns the width in bytes of one pixel row (ULONG).
  473.    JPG_ColourSpace   - Returns the type of colour space stored in the jpeg
  474.                        image (see jpeg.h for result codes) (UBYTE)
  475.  
  476.   Modifiers (used, but not saved in the jpeg handle):
  477.    JPG_ScaleNum      - Return values as though scaled with this value.
  478.    JPG_ScaleDenom    - Return values as though scaled with this value.
  479.  
  480.  The jpeg code has a limition on scaling where, num must always be 1 and
  481.  denom can be either: 1, 2, 4, or 8.
  482.  
  483.  Only JPEGDecHandles can have values read from them, JPEGComHandle passed
  484.  to this function returns a JPGERR_NONE and the taglist remains untouched.
  485.  
  486.    INPUTS
  487.  jph - pointer to a struct JPEGDecHandle.
  488.  taglist - pointer to an optional tag list specifying what data items to
  489.             retrieve for this jpeg handle.
  490.  
  491.    RESULT
  492.  err - if non NULL contains an error code. (For a complete list of error
  493.        codes, see jpeg.h)
  494.  
  495.    WARNING
  496.  
  497.    BUGS
  498.  
  499.    EXAMPLE
  500.  
  501.  err = GetJPEGInfo( jph, JPG_Width, &x, JPG_Height, &y, TAG_DONE );
  502.  
  503.    SEE ALSO
  504.  
  505.  
  506.